Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
What It Does
ODMath is a set of utilities for working with the the OpenDoc numeric types ODFixed (aka ODCoordinate) and ODFract. These are both 32-bit fixed-point numbers. These types both represent real numbers that have been scaled up and rounded to integers. ODFixed has been scaled up by a factor of 2^16 (65,536) while ODFract has been scaled up by 2^30 (1,073,741,824). Another way to look at it is that an ODFixed has an implicit “binary point” between the upper and lower word, while an ODFract has the binary point two bits from the most significant bit.
This gives an ODFixed a range of -32768.0 to nearly +32768, with a resolution of 1/32,768 (about 3x10^-5). ODFract has a range of only -2 ... +2, but with a resolution of 1/1,073,741,824 (about 10^-9).
In addition, there is some support for the type ODWide, which is a 64-bit integer. ODWide is not used directly in the OpenDoc API, but is useful for storing intermediate results in computations on integers, ODFixeds and ODFracts. The utility LineOps.cpp has examples of this.
Constants
Several common values are available as named constants:
kODFixed1
kODFixedHalf
kODFract11
kODFixedInfinity — the largest possible positive ODFixed value
kODFixedMinusInfinity — the largest possible negative ODFixed value
Conversion Functions
ODFixedRound converts an ODFixed to an integer, rounding toward the nearest integer.
ODIntToFixed converts an integer to an ODFixed.
ODFixedToFract converts an ODFixed to an ODFract.
ODFractToFixed converts an ODFract to an ODFixed.
ODFixedToFloat converts an ODFixed to a floating point number.
ODFloatToFixed converts a floating point number to ODFixed.
All of these functions are implemented inline as simple shifts, multiplies and divides. They do not perform any range checking and will return bogus values if the input value is not in the correct range.
There are some missing functions here, such as ODFractToFloat and ODFloatToFract. They're left as exercises for the reader, and are easy to figure out if you look at the definitions of the existing conversions.
Arithmetic
Fixed point numbers can be added and subtracted like integers, so you don't need any special functions for addition or subtraction. You can also multiply/divide an ODFixed or ODFract with an integer by using regular integer multiplication or division.
ODFixedMultiply, ODFixedDivide multiply and divide ODFixeds. They return the appropriate “infinity” value (see the Constants section above) in the case of overflow.
ODFractMultiply, ODFractDivide multiply and divide ODFracts, with similar overflow behavior.
ODFractSinCos computes the sine and cosine of an angle. The angle is an ODFixed whose units are radians, and the results are ODFracts.
ODWide Operations
ODWideCompare compares two ODWide values for equality.
ODWideIsLong determines whether an ODWide value is within the range of a long integer. (If so, the integer value is in the “lo” field of the ODWide struct.)
ODWideShift shifts the bits of a wide integer. A positive shift makes the number larger, a negative shift makes it smaller.
ODWideNegate flips the sign of an ODWide value (subtracts it from zero.)
ODWideAdd, ODWideSubtract operate on two ODWide values.
ODWideMultiply multiplies two 32-bit integers and produces an ODWide result.
ODWideDivide divides an ODWide by a 32-bit integer. It has a third pointer parameter in which the remainder is returned. If you don't care about the remainder, pass kODIgnoreRemainder in the 'remainder' parameter.
ODWideSquareRoot takes the square root of an ODWide, returning an integer.
